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3. Evaluation 

Ihc following is a complete description of the actions u«kcn by the cvaliiator, given a Jbrm to 
evaluate. 

inform is a number, the result hfonn. 

Uform is a string, the result hfonn. 

\f form is a self-evaluating symbol (nil, t or a keyword such as :foo), then fmn itself is the 
result. 

If form is any other symbol, the result is tlie value of form, considered as a variable. If 
form's value is void, an error is signaled. The way symbols are bound to values is explained in 
section 3.1, page 25 below. 

Uform is not any of the above types, and is not a list, fonn itself is the result. 

In all remaining cases, form is a list. 1'he cvaluator examines the car of the list to figure out 
what 10 do next. There arc tlirce possibilities: this form may be a special form, a macro form, 
or a plain old function form. If tlic car is an explicit function such as a list starting with lambda, 
the forni is a function form. If it is a symbol, tilings depend on the symbol's function definition, 
which may be a special form definition (see page 233), a macro definition, or an ordinary 
function. 

If fonn is a special fonn, then it is handled accordingly; each special form works differently. 
All of them are documented in this manual. The internal workings of special forms are explained 
in more detail on page 233, but tliis hardly ever affects you. 

If form is a macro form, then the macro is expanded as explained in chapter 18. 

\f fonn is a function form, it calls for the application of a fimction to arguments. The car of 
fonn is a function or the name of a function. 'Hie cdr of fonn is a list of subfonns. Tlie 
subforms arc evaluated, sequentially, and each produces one argument for the function. TTie 
function is tiien applied to diosc arguments. Whatever results the function returns are the values 
of tlie original j?>mi. 

'Tlicre is a lot more to be said about evaluation. ITie way variables work and the ways in 
which they arc manipulated, including the binding of arguments, is explained in section 3.1, page 
25. A basic explanation of fimciions is in section 3.3, page 38. The way functions can return 
more than one value is explained in section 3.7, page 55. The description of all of tlic kinds of 
functions, and the means by which they are manipulated, is in chapter 11. Macros are explained 
in chapter 18. The evalhook facility, which lets you do something arbitrary whenever the 
evaluator is invoked, is explained in section 30.12, page 748. Special forms are described all over 
the manual: each special form is in the section on the facility it is part of. 
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3.1 Variables 

In /cialisp, variables arc implemented using symbols. Symbols arc used for many tilings in 
the language, such as naming functions, naming special forms, and being keywords; they are. also 
useful to programs written in Lisp, as parts of d<Jta structures. But when a symbol is evaluated, 
its value as a variable is taken. 



3.1.1 Variables and Bindings 

Iherc are two dilfcrcnt ways of changing the value of a variable. One is to set tlie variable. 
Setting a variable changes its value to a new I. isp object, and the previous value of the variable is 
forgotten. Setting of variables is usually done with the setq special form. 

The other way to change the value of a variable is with binding (also called lambda-binding). 
We say that a variable is bound (past participle of active verb) by the action of binding; we also 
say that the variable is bound (state of being) after a binding has been made. When a binding is 
made, the variable's old binding and value are hidden or shadowed by a new binding, which 
holds a new value. Setting a variable places a new value into the current binding; it does not 
change which binding is current. In addition, shadowed bindings' values are not affected by 
setting tJie variable. Hinding a variable does not affect the value in the old current binding but 
tliat binding ceases to be current so tlic value no longer applies. 

1 he action of binding is always followed eventually by the action of unbinding. 1'his discards 
the current binding of tlie variable, with its value. The previous binding becomes current again, 
and the value in it— unchanged since t]ie newer binding was made, in normal operation— is visible 
again. 

Binding is normally done on entry to a function and by certain special forms (let, do, prog 
and others). The bindings arc unbound on exit from the function or the special form, even 
nonlocal exit such as go, return or throw. The function or special form is said to be the scope 
of the bindings made therein. 

Here is a simple example of making a binding, shadowing it, unshadowing it, examining it, 
and unbinding it. The inner, shadowing binding is made, examined, set, examined and unbound, 
(let ((a 5)) 

(print a) ;prints5 

(let ((a "foo")) 

(print a) ;prints"foo" 

(setq a "bar") 
(print a)) ;prints "bar" 

(print a)) ;prints6 

Every symbol has one binding which was never made and is never unbound. ITiis is the 
global binding. This binding is current whenever no other binding has been esti^blished that 
would shadow it. If you type (setq x 5) in the Lisp listen loop, you set the global binding of x. 
Programs often set global bindings permanently using defvar or one of its cousins (page 33). 
setq -globally and related functions can be used to set or refer to the global binding even when it 
is shadowed (page 35). 
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(defvar a 5) : sets llic global binding 

(let {(a t)) 

(print a)) ; prints t 

a => 5 : the global binding is visible again 

A binding docs not need to have an actual value. It can be voui instead. The variable is also 
called void. Actually, a void binding contains a vveird internal value, which the system interprets 
as meaning "there is no value here". (This is the data type code dtp-null, page 271). Reference 
to a variable whose current binding is void signals an error. In fact, nearly all variables' global 
bindings are void; only those that you or the system have set are not void, variable- 
makunbound makes tJic current binding of a variable void again (page 31). 

'Void' used to be called 'unbound', and most function names, error messages and 
documentation still use the term 'unbound'. The variable is also called 'imbound'. The term 
'void" is being adopted because it is less ambiguous. 'Utibound' can mean 'void', or 'not bound' 
(no binding established), or ihc past participle of 'unbind'. 

All bindings except global binding have a limited scope: one function or special form. TTiis 
docs not fully specify tlic scope, however: it may be lexical or dynamic. When a binding has 
lexical scope, it is visible only from code written within tlic function or special form tliat 
established it. Subroutines called from within the scope, but which arc written elsewhere, never 
see the lexical binding. By contrast, a dynamic binding is visible the whole time it exists (except 
when it is shadowed, of course), which includes time spent in subroutines called from within the 
binding constmct. ITic global binding of a symbol can be regarded as a dynamic binding tliat 
lasts from die beginning of the session to the end of the session. 

Lexical and dynamic bindings arc made by die same kinds of fiinction definitions and special 
forms. By default, the bindings are lexical. You request a dynamic binding instead using a 
special-declaration at die beginning of the body of the function definition or special form. Also, 
some symbols are marked globally special; every binding of such a symbol is dynamic. ITiis is 
what defvar, etc., do to a syinbol. Dynamic bindings are also called special bindings, and the 
variable bound is called a .special variable. Hach use of a symbol as a variable (this includes 
setting as well as examining) is also marked as lexical or dynamic by the same declarations. A 
dynamic use sees only dynamic bindings, and a lexical use sees only lexical bindings. 

In die examples above it makes no diflTcrcnce whether die bindings of a are lexical or 
dynamic, because all die code executed between die binding and unbinding is also written 
lexically within the let which made die binding. Here is an example where it makes a difference: 

(defun foo () 
(print a)) 

(let ((a 5)) 
(foo)) 

»Error: the variable A is used free but not special. 
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if ihc inlonlion is that 5 bo printed, a dynamic binding is required. A dynamic binding 
would remain visible for all the execution from the entry to the let to the exit from the let, 
including the execution of the definition of foo. Actually, the default is to do lexical binding. 
Since the binding of a is lexical, it is visible only for the evaluation of expressions written inside 
the let, which docs not include the body of foo. In fact, an error happens when foo evaluates a, 
since a there is supposed to be lexical and no lexical binding is visible. If you compile foo, you 
get a compiler warning about a. 

The use of a inside foo, not lexically within any binding of a, is called free, and a is called 
a free vuruible of foo. l-'ree variables arc erroneous unless they are special. Strictly speaking, it is 
erroneous to type (setq x 5) at lop level in the l.isp listener if x has not been made globally 
special, but this is perniitted as an exception because it is so often useful. 

One way to make tlic example work is to make a globally special: 

(defvar a) 

(defun foo {) (print a)) 

(let ((a 5)) 
(foo)) 

prints 5. The global spccialncss of a tells let to make a dynamic binding and tells the evaluation 
of a in foo to look for one. 

Another way is with declarations at the point of binding and the point of use: 

(defun foo () 

(declare (special a)) 
(print a)) 

(let ((a 5)) 

(declare (special a)) 
(foo)) 

A declaration at the point of binding affects only that binding, not other bindings made 
within it to shadow it. Another way of stating this is that a binding is affected only by a 
declaration in the construct that makes tlic binding, not by declarations in surrounding constructs. 
ITius, 
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(let {(a 5)) ; this binding is dynamic 

(declare (special a)) 

(let ((a "foo")) ;lJiis binding is lexical 
no (Jcclaralion here 

... a ... : this reference is lexical since 

... ; ihc innemiosl binding is lexical 
(let () 

( declare ( special a) ) 

... a ... ;Lhis reference is dynamic, and sees value 5 

(Currently, for historical compatibility, bindings are affected by surrounding declarations. 
However, whenever this makes a difTcrcnce, the compiler prints a warning to inform the 
programmer ihat tlie declaration should be moved.] 

Hie -classical case where dynamic binding is useful is for parameter variables like *read- 
base*: 

(let ( ( *read-base* 16.)) 
(read)) 
reads an expression using hexadecimal numbers by default. *read-base* is globally special, and 
the subroutine of read tliat reads integers uses *read-base* free. 

Here is an example where lexical bindings are desirable: 

(let ((a nil)) 

(mapatoms (function (lambda (symbol) (push symbol a)))) 
a) 

Because the reference to a from within tlie internal function is lexical, the only binding it can 
sec is tlie one made by this let. mapatoms cannot interfere by binding a itself. Consider: if 
mapatoms makes a lexical binding of a. it is not visible here because this code is not written 
inside the definition of mapatoms. If mapatoms makes a dynamic binding of a, it is not visible 
here because the reference to a is not declared special and Uierefore sees only lexical bindings. 

The fact that function is used to mark the internal function is crucial. It causes the lexical 
environment appropriate for the function to be combined with tlie code for the ftinction in a 
lexical closure, which is passed to mapatoms. 

The last example shows downward use of lexical closures. Upward use is also possible, in 
which a function is closed inside a lexical environment and tlien preserved after the binding 
construct has been exited. 



PS:<L.MAN>Fl>KVA.'rKXT.46 8-JUN-84 



.isp Machine Mamiijl 2^) Variables 



(defun mycons (ad) 
(function ( lambda (x) 

(cond ((eq x 'car) a) 

((eq X 'cdr) d))))) 

(defun mycar (x) (funcall x 'car)) 
(defun mycdr (x) (funcall x 'cdr)) 

(setq mc (mycons 4 t)) 

(mycar mc) => 4 
(mycdr mc) => t 

mycons returns an object that can be called as a function with one argument. This object 
retains a pointer to a lexical environment that has a binding for a and a binding for d. The 
fiHiction mycons that made those bindings has been exited, but this is irrelevant because the, 
bindings were not dynamic. Since the code of tJie lambda-expression is lexically within the body 
of mycons, that function can see tlie lexical bindings made by mycons no matter when it is 
called. The function returned by mycons records two values and can deliver either of them when 
asked, and is therefore analogous to a cons cell. 

Only lexical bindings arc transferred automatically downward and upward, but dynamic 
bindings can be used in the same ways if explicitly requested tlirough the use of tlic function 
closure. See chapter 12, page 250 for more information. 

Dynamic bindings, including the global binding, are stored (unless shadowed) in a particular 
place: die symbol's value cell. This is a word at a fixed offset in the symbol itself When a new 
dynamic binding is made, the value in tlic value cell is saved away on a suick called the special 
pdl. The new bindings value is placed in tlie value cell. When the new binding is unbound, the 
old binding's value is copied off of the special pdl, into tlie value cell again. The function 
symeval examines the value cell of a symbol chosen at run time; therefore, it sees tlie current 
dynamic binding of the symbol. 

Lexical bindings are never stored in the symbol's value cell. The compiler stores them in 
fixed slots in stack frames. 'ITie interpreter stores them in alists Uiat live in tlie stack. It should 
be noted that if tlie lexical binding is made by compiled code, then all code tliat ought to see the 
binding is necessarily also compiled; if the binding is made by interpreted code, then all code 
tliat ought to see the binding is necessarily interpreted. ITierefore, it is safe for the com^piler and 
interpreter to use completely different techniques for recording lexical bindings. 

Lexical binding is the default because the compiler can find with certainty all the places where 
a lexical binding is used, and usually can use short cuts based on this certainty. For dynamic 
bindings slow but general code must always be generated. 
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3.1.2 Sell inj; Variables 

Here arc the consiructs used for sotting variables. 

setq {variable value]... Special form 

The setq special form is used to set the value of a variable or of many variables. The 
first value is evaluated, and the first variable is set to the result. Then the second value is 
evaluated, the second variable is set to tlie result, and so on for all the variable/value 
pairs, setq returns the last value, i.e. the result of the evaluation of its last subfonn. 
I Example: 

(setq X {+ 3 2 1) y (cons x nil)) 
X is set to 6, y is set to (6). and the setq form returns (6). Note that the first variable 
was set before the second value form v^as evaluated, allowing that form to use the new 
value of X. 

psetq {variable value}... Macro 

A psetq form is just like a setq form, except that the variables arc set "in parallel"; first 
all of tlic value forms are evaluated, and tlicn Uie variables arc set to the resulting values. 
Hxamplc: 

(setq a 1) 

(setq b 2) 

(psetq abba) 

a => 2 

b => 1 

variable-location symbol Specialform 

Returns a locative to the cell in which die value of symbol is stored, symbol is an 
uncvaluatcd argument, so the name of the symbol must appear explicitly in tlic code. 

For a special variable, this is equivalent to 

(value-eel 1 -location 'symbol) 
For a lexical variable, tlie place where the value is stored is a matter decided by the 
interpreter or tlie compiler, but in any case variable- location nevertheless returns a 
pointer to it. 

In addition, if symbol is a special variable that is closed over, the value returned is an 
external value cell, the same as the value of locate-in -closure applied to the proper 
closure and symbol. This cell always contains die closure binding's value, which is current 
only inside the closure. See page 251. 

varlable-boundp symbol Specialform 

t if variable symbol is not void. It is equivalent to 

(location-boundp (variable-location symbol)) 
symbol is not evaluated. 
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variable- ma kunbound symbol Special form 

Makes syml)ol\ ciincnl binding void. It is equivalent to 

( location-makunbound (variable-location symbol)) 
symbol is not evaluated. 

3.1.3 Variable Binding Constructs 

Mere arc ilie constructs used for binding variables. 

let {{var value)...) body... Special fonn 

Is used to bind some variables to some objects, and evaluate some forms (the body) in 
the context of those bindings. A let form looks like 
(let {{var I vfonnl) 
( var2 vfonn2 ) 

bforml 

bfonn2 

...) 
When this fonn is evaluated, first Uie vfonns (the values) arc evaluated. Then the vars are 
bound to the values returned by tlic corresponding vfonns. Thus tlie bindings happen in 
parallel; all the vforms are evaluated before any of the vars are bound. Finally, the 
bforms (the body) arc evaluated sequentially, the old values of tlic variables arc restored, 
and tlic result of tlic last bform h returned. 

You may omit the vfonn from a let clause, in which case it is as if the vfonn were nil: 
tlic variable is bound to nil. Furtliermorc, you may replace the entire clause (the list of 
the variable and fonn) with just the variable, which also means that die variable gets 
bound to nil. Example: 

(let ((a (+ 3 3)) 

(b 'foo) 

(c) 

d) 

Within the body, a is bound to 6, b is bound to foo, c is bound to nil, and d is bound 
to nil. 

let* {{var value)...) body... Special form 

let* is the same as let except that the binding is sequential. Each var is bound to the 
value of its vform before the next vfonn is evaluated. This is useful when the computation 
of a \fonn depends on tlie value of a variable bound in an earlier vform. Example: 
(let* ((a (+ 1 2)) 
(b (+ a a))) 

Within the body, a is bound to 3 and b is bound to 6. 
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let-1f condiiion ({\w value)...) body... Spcmlfom 

let- if is ii variani of let in which the binding of variables is condiiional. The let-if 
special fomi. typically written as 
(let-if amd 

{ { V(7/"/ \'<7/-/) ( vur-2 Yal-2) . . . ) 
body. ..) 
first evaluates the predicate form vond. If tlic result is non-nil, the value forms val-l, 
vnl-2, etc. are evaluated and then the variables vat-l, var-2, etc. arc bound to them. If 
the result is nil, tJic wm and \ah are ignored, l-inally the body forms are evaluated. 

The bindings are always dynamic, and it is ihe user's responsibility to put in appropriate 
declarations so ihat the body forms consider the variables dynamic. 

let-globally {(\ar vahu)...) body... ^^acw 

let-globally-lf condiiion {{var vohw)...) body... Macro 

let-globally is similar in form to let (see page 31). The difference is Uiat let-globally 
does not bind die variables; instead, il saves tlie old values and scis the variables, and 
sets up an unwind-protect (see page 82) to set tJiem back. The important consequence is 
that, with let-globally, when the current sUick group (sec chapter 13, page 256) co-calls 
some other sUick group, the old values of tlie variables are not restored, llius let- 
globally makes the new values visible in all sUick groups and processes that don't bind the 
variables tliemselves, not just in the current sUick group. Therefore, let-globally can be 
used for communication between stack groups and between processes. 

let-globally-if modifies and restores the variables only if the value of condition is non-nil. 
The body is executed in any case. 

Since let-globally is based on setq, it makes sense for both lexical and dynamic 
variables. But its main application exists only for dynamic variables. 

The globally in let-globally does not mean the same thing as the globally in setq- 
globally and related functions. 

ppogv symbol-list value-list body... Special fonn 

progv is a special form to provide the user with extra control over binding. It binds a 
list of variables dynamically to a list of values, and then evaluates some forms. ITic lists 
of variables and values are computed quantities; this is what makes progv different from 
let, prog, and do. 

progv first evaluates symbol-list and value-list, and then binds each symbol to the 
corresponding value. If too few values are supplied, the remaining symbols' bindings are 
made empty. If too many values are supplied, the excess values arc ignored. 

After the symbols have been bound to the values, the body forms arc evaluated, and 
finally the symbols' bindings are undone. 1 he result returned is the value of the last form 
in the body. Assuming tliat the variables a, b, foo and bar are globally special, we can 
do: 
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(setq a 'foo b 'bar) 

(progv { list a b 'b) ( list b) 
(list a b foo bar)) 
=> (foo nil bar nil) 

During the evaluation of ihe body of this progv, foo is bound to bar, bar is bound to 
nil, b is bound to nil, and a retains its top-level value foo. 

progw vars-iwd-vah-form body... Special form 

progw is like progv cxeepl that it has a dillerent way of deeiding which variables to bind 
and what values to give them. Like progv, it always makes dynamic bindings. 

hirst, vars- and- val-fonm- form is evaluated, its value should be a list that looks like the 
first subfomi of a let: 

{{varl mi-form- 1) 

( mr2 vaI-form-2) 

...) 
Hach clement of this list is processed in turn, by evaluating the val-form and binding tlie 
var dynamically to tJic resulting value. Finally, Uie body foms arc evaluated sequentially, 
the bindings are undone, and tlie result of the last form is returned. Note that the 
bindings are sequential, not parallel. 

This is a very unusual special form because of tJic way die c valuator is called on the 
result of an evaluation, progw is useful mainly for implementing special forms and for 
functions part of whose contract is that tJicy call die interpreter. For an example of the 
latter, see sys:*break-bindings* (page 797); break implements Uiis by using progw. 

See also %bind (page 284), which is a subprimitive that gives you maximal control over 
binding. 

3.1.4 Defining Global Variables 

Here arc the constructs for defining global variables. F^ich makes the variable globally special, 
provides a value, records documentation, and allows tlic editor to find where all this was done. 

defvar variable [iniliaHalue] [documenlation] Macro 

defvar is the recommended way to declare the use of a global variable in a program. 
Placed at top level in a file, 

(defvar variable initial-value 
"documentation*') 
declares variable globally special and records its location in the file for the sake of the 
editor so that you can ask to see where the variable is defined. The documenUition string 
is remembered and returned if you do (documentation 'variable 'variable). 

If variable is void, it is initialized to the result of evaluating the form initial-value, initial- 
value is evaluated only if it is to be used. 
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ir you do not wish lo give variable any inilial value, use the symbol :unbound as the 
initial-value form. This is ireaicd specially; no allenipl is made to evaluate :unbound. 

Using a documentation siring is better than using a comment to describe the use of the 
variable, because the documentation string is accessible to system programs that can show 
the documentation to you while you are using the machine. While it is still permissible to 
omit inilial-value and the documentation string, it is recommended that you put a 
dociniientation string in every defvar. 

defvar should be used only at top level, never in function definitions, and only for global 
variables (those used by more than one function), (defvar foo 'bar) is roughl> equivalent 

to 

(declare (special foo)) 

(if (not (boundp 'foo)) 

( setq foo 'bar) ) 

if defvar is used in a patch file (see section 28.8, page 672) or is a single form (not a 
region) evaluated with the editor's compile/evaluate from buffer commands, if tlicrc is an 
initial- value the variable is always set to it regardless of whether it is void. 

def const variable inilial-value [documentation] Macro 

defparameter variable initial-value [documentation] Macro 

defconst is tlie same as defvar except tliat if an initial value is given the variable is 
always set to it regardless of whether it is already bound. The rationale for Uiis is tliat 
defvar declares a global variable, whose value is initialized to something but will then be 
changed by tlie functions that use it to mainUiin some state. On the other hand, 
defconst declares a constant, whose value will be changed only by changes to the 
program, never by die operation of the program as written, defconst always sets the 
variable to the specified value so tliat if, while developing or debugging the program, you 
change your mind about what the constant value should be, and then you evaluate the 
defconst form again, die variable gets Uic new value. It is not tlie intent of defconst to 
declare diat the value of variable will never change; for example, defconst is not a 
license to the compiler to build assumptions about the value of variable into programs 
being compiled. 

As with defvar, you should include a documentation string in every defconst. 

defconstant symbol value [documentation] Macro 

Defines a true constant. The compiler is permitted to assume it will never change. 
Therefore, if a function that refers to symboFs value is compiled, the compiled function 
may contain value merged into it and may not actually refer to symbol at run time. 

You should not change the value of symbol except by reexecuting die defconstant with a 
new value. If you do this, it is necessary to recompile any compiled functions diet refer 
to symbol 's value. 
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3.1.5 The Global Binding 

I'liis section describes fiinclioiis which examine or set the global binding of a variable even 
when il is shadowed and cannot be accessed simply by evaluating the variable or selling it. 

The primary use of these functions is for inil files to set variables which are bound by the 
load function, such as package or base, (setq package (find -package 'foo)) executed from a 
file being loaded has no ellect beyond the end of loading that file, since it sets the binding of 
package made by load. However, if you use setq -globally instead, the current binding in effect 
during loading is actually not changed, but when the load exits and the global binding is in ellect 
again, foo will become the current package. 

setq-globally [symbol value}... Mcwro 

Sets each syinbol\ global binding to the value that follows. The iw/wc's arc evaluated but 
tlie symbors arc not. 

set-globally symbol value 

Sets the global binding of symbol to value. 

makunbound-globally symbol 

Makes tlic global binding of symbol be void. 

boundp-globally symbol 

Returns t if the global binding of symbol is not void. 

symeval -globally symbol 
symbol -value-globally symbol 

Return tlie value of die global binding of symbol. An error is signaled if the global 

binding is void. 

See also pkg -goto -globally (page 638), a "globally" version of pkg-goto. Note that let- 
globally is not analogous to these functions, as it modifies the current bindings of symbols rather 
tlian their global bindings. This is an unfortunate collision of naming conventions. 

3.2 Generalized Variables 

In Lisp, a variable is something that can remember one piece of data. The primary 
conceptual operations on a variable are to recover that piece of data and to change it. These 
might be called access and update. The concept of variables named by symbols, explained above, 
can be generalized to any storage location that can remember one piece of data, no matter how 
that location is named. 

For each kind of generalized variable, there are typically tliree functions which implement the 
conceptual access, update and locate operations. For example, symeval accesses a symbol's value 
cell, set updates It, and value-cell-location returns the value cell's location, array-leader 
accesses the contents of an array leader element, store -array -leader updates it, and ap-leader 
returns tlic location of the leader element, car accesses tlie car of a cons, rplaca updates it, and 
car- location returns the location of the car. 
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kiithcr than thinking i)f this as ivvu functions, which operate on a storage location somehow 
deduced from iheir arguments, we cm shift our point of view and ihink of liie access function as 
a name for the storage location. Thus (symeval 'foo) is a name for tlic value of foo, and (aref a 
105) is a name for the 105th clement of the array a. Rather than having to remember the 
update function associated with each access function, we adopt a uniform way of updating storage 
locations named in this way. using the self special form. This is analogous to the way we use 
the setq special form to convert the name of a \ariable (which is also a form which accesses it) 
into a form that updates it. In fact, self is an upward compatible generalization of setq. 
Similarly, the location of the generalized variable can be obtained using the locf construct. 

3.2.1 self 

S€Jtf is the construct for storing a new value into a generalized variable which is identified by 
the form which would obtain Uic current value of the variable. For example, 

(setf (car x) y) 
stores tlic value of y into tlic car of the value of x. 

setf is particularly useful in combination with structure-accessing macros, such as those created 
with defstruct, because the knowledge of the representation of tlie structure is embedded inside 
the macro, and tlie programmer shouldn't have to know what it is in order to alter an clement of 
the stixicture. 

setf is actually a macro which expands into tlie appropriate update code. It has a database, 
explained in section 18.10, page 345, that associates from access functions to update functions. 

setf {place value}... Macro 

Takes a form called place that accesses something and "inverts" the fonn to produce a 
corresponding form to update the thing. A setf expands into an update form, which 
stores the result of evaluating the fonn value into the place referenced by the place. If 
multiple place's and value's are specified, each one specifies an update, and each update 
is done before tlie following updates' arguments arc computed. 
Examples: 

(setf (array-leader foo 3) 'bar) 

==> (store-array-leader 'bar foo 3) 

(setf a 3) ==> (setq a 3) 

(setf (plist 'a) '(foo bar)) ==> (setplist 'a '(foo bar)) 

(setf (aref q 2) 56) ==> ( sys :set-aref q 2 56) 

(setf (cadr w) x) ==> (sys:setcdr (cdr w) x) 

The value of a setf form is always the value stored by the last update it performs. Thus, 
(setf (cadr w) x) is not really die same as (rplaca (cdr w) x), because the setf returns x 
and the rplaca returns w. In fact, the expansion of setf of cdr uses an internal function 
si:setcdr which exists specifically for this purpose. 

If place invokes a macro or a substitutabic function, then setf expands the place and 
starts over again. ITiis lets you use setf together witli defstruct accessor macros. 



PS:<L.MAN>FD-HVA.THX'r.46 8-JUN-84 



I isp M.ichinc Maiuuil 37 Gonciali/cd Variiihlcs 



sysrunknownsetf reference (error) ComUiion 

sys:unknown-1ocf -reference (error) Condiikm 

Tlicsc arc signaled when setf or locf does not know how to expand the place. Ilie :form 

operation on the condition instance relinns the access- form . 

psetf {place value]... Macro 

Stores each value into tiie corresponding place, with the changes taking elTect in parallel. 

IhlLS, 

(psetf (car x) (cdr x) (cdr x) (car x)) 
interchanges the car and cdr of x. 

The SLibforms of the places, and tJie values, are evaluated in order; thus, in 
(psetf (aref a (tyi)) (tyi) 

(aref b (tyi)) (aref a (tyi))) 
the first input character indexes a, the second is stored, the third indexes b, and Uic 
fourth indexes a. The parallel nature of psetf implies that, should the first and fourth 
characters be equal, tlie old value of tliat element of a is what is stored into the array b, 
rather Uian tlic new value which comes from tlie second character read. 

shiftf place... ^focro 

Sets tlie first place from tlie second, tJic second from the third, and so on. The last place 
is not set, so it doesn't really need to be a setf able place; it can be any fonn. The 
value of tlie shiftf form is tlie old value of die first place, llius, 

(shiftf X (car (foo)) b) 
evaluates (foo), copies the car of that value into x, copies b into die car of that value, 
then returns the former value of x. 

rotatef place.., ^f^cro 

Sets the first place from die second, tlie second from Uie third, and so on, and sets the 
last place from Uie old value of tlie first place. Thus, the values of the place's are 
permuted among the place's in a cyclic fashion. 

With only two place's, their values arc exchanged: 

(rotatef (car x) (cdr x)) 
is equivalent to the psetf example above. 

swapf placel place2 Macro 

Exchanges die contents of placel and place2. This is a special case of rotatef. 

1ncf place [amount] Macro 

Increments die value of a generalized variable, (incf rej) increments die value of refhy 1. 
(incf ref amount) adds amount to ref and stores die sum back into ref. ITie incf form 
returns die value after incrementation. 

incf expands into a setf form, so re/ can be anything diat setf understands as its place. 
Incf is defined using define-modify-macro, page 349. 
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decf place [cimoum] Macro 

Docrcmcnts ihc viiliic of a gcnciali/.ed variable. Just like incf except that amouni (or 1) is 
subtracted rather than added. 

See also push (page 88), pop (page 88). pushnew (page 107). getf (page 115) and remf 
(page 115). 

3.2.2 locf 

iksides the access and iipdalc conceptual operations on generalized variables, there is a third 
basic operation, which we might call locale. Given the name of a storage cell, the locate 
operation returns the address of that cell as a locative pointer (see chapter 14, page 267). This 
locati>e pointer is a first-class I. isp data object which is a kind of reference to the cell. It can be 
passed as an argument to a function which operates on any cell, regardless of where tlic cell is 
found. I,t can be used to binJ the contents of the cell, just as special variables arc bound, using 
tlie %bind subprimitive (see page 284). 

Of course, this can work only on generalized variables whose implementation is really to store 
their value in a memory cell. A generalized variable with an update operation that encrypts the 
value and an access operation that decrypts it could not have tlie locale operation, since the value 
per se is not actually stored anywhere. 

locf place Macro 

locf takes a fonn that accesses some cell, and produces a corresponding form to create a 

locative pointer to that cell. 

Examples: 

(locf (array-leader foo 3)) ==> (ap-leader foo 3) 

(locf a) ===> (value-cell-location 'a) 

(locf (plist *a)) ==> (property-cell-location 'a) 

(locf (aref q 2)) ==> (aloe q 2) 

If place invokes a macro or a substitutable function, then locf expands the place and 
starts over again. This lets you use locf together with defstruct accessor macros. 

3.3 Functions 

In the description of evaluation on page 24, we said that evaluation of a function form works 
by applying the function to the results of evaluating the argument subforms. What is a function, 
and what does it mean to apply it? In Zctalisp tliere are many kinds of fimctions, and applying 
them may do many different kinds of tilings. For full details, see chapter 11, page 223. Here we 
explain the most basic kinds of functions and how they work. In particular, this section explains 
lambda lists and all their important features. 

The simplest kind of user-defined function is the lambda- expression, which is a list that looks 
like: 

(lambda lambda-list bodyl body2...) 
The first element of the lambda-expression is the symbol lambda; the second element is a list 
called the lambda list, and the rest of die elements are called the body. 'Ihc lambda list, in its 
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simplest form, is jiisl a list of variables. Assuming that this simple form is being used, here is 
what happens when a lambda expression is applied to some .irguments. I'irst, the number of 
arguments and the number of variables in the lambda list must be the same, or else an error is 
signaled, luieh variable is bound to the corresponding argument value, i'hen the forms of the 
body are evaluated sequentially. After this, ihe bindings are all undone, and the value of the last 
form in the body is returned. 

This may sound something like the description of let, above. The most important diHcrcncc 
is that ihe lambda-expression is not a form at all; if you try to evaluate a lambda-expression, you 
get an error because lambda is not a defined function. The lambda-expression is a function, not 
a form. A let form gets evaluated, and the values to which the variables are bound come from 
the evaluation of some subforms inside the let form; a lambda-expression gets applied, and the 
values are the arguments to which it is applied. 

ihe variables in the lambda list arc sometimes called parameters, by analogy with other 
la^iguagcs. Some other terminologies would refer to tlicsc as formal parameters, and to arguments 
as actual parameters. 

Lambda lists can have more complex structure than simply being a list of variables. Iliere are 
additional features accessible by using certain keywords (which smrt with &) and/or lists as 
elements of tlie lambda list. 

Ihe principal weakness of simple lambda lists is that any function written with one must only 
take a certain, fixed number of arguments. As we know, many very useful functions, such as 
list, append, +, and so on, accept a varying number of arguments. Maclisp solved this problem 
by the use of lexprs and Isubrs, which were somewhat inelegant since tlie parameters had to be 
referred to by numbers instead of names (e.g. (arg 3)). (For compatibility reasons, ZcUilisp 
supports lexprs, but they should not be used in new programs.) Simple lambda lists also require 
tliat arguments be matched with parameters by tlieir position in tlie sequence. Ihis makes calls 
hard to read when tlicre arc a great many arguments. Keyword parameters enable the use of 
other, more readable styles of call. 

In general, a function in Zetalisp has zero or more positional parameters, followed if desired 
by a single rest parameter, followed by zero or more keyword parameters. The positional 
parameters may be required or optional, but all the optional parameters must follow all the 
required ones. The required/optional distinction does not apply to tlie rest parameter; all 
keyword parameters arc optional. 

The caller must provide enough arguments so that each of the required parameters gets 
bound, but he may provide extra arguments for some of tlie optional parameters. Also, if tlierc 
is a rest parameter, he can provide as many extra arguments as he wants, and the rest parameter 
is bound to a list of all these extras. Optional parameters may have a defauU-fonn, which is a 
form to be evaluated to produce tJie default value for the parameter if no argument is supplied. 

Positional parameters are matched with arguments by the position of the arguments in the 
argument list. Keyword parameters are matched with their arguments by matching tlie keyword 
name; the arguments need not appear in the same order as the parameters. If an optional 
positional argument is omitted, then no further arguments can be present. Keyword parameters 
allow the caller to decide independently for each one whether to specify it. 
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Here is the exact algorithm used Id nialcli up the argumems with ihe parameters: 

Required positional parameters: 

The first required positional parameter is bound to the first argument, apply continues to 
bind successive required positional parameters to the successive arguments. \i\ during this 
process, there are no arguments left but there are still some required parameters which 
have not been bound yet, it is an errt)r ("too few arguments"). 

Optional positional parameters: 

After all required parameters are handled, apply continues with the optional positional 
parameters, if any. it binds each successive parameter to the next argument. If, during 
this process, there are no arguments left, each remaining optional parameter's default-form 
is evaluated, and the parameter is bound to it. This is done one parameter at a time; 
that is. first one default-form is evaluated, and then the parameter is bound to it, then 
the next default-form is evaluated, and so on. This allows lJie default for an argument to 
depend on tlie previous argument. 

After the positional parameters: 

Now, if there are no remaining parameters (rest or keyword), and there are no remaining 
arguments, we arc finished. If tlierc arc no more parameters but dierc are still some 
arguments remaining, an error is signaled ("too many arguments"). If parameters remain, 
all the remaining arguments are used for bolh Uic rest parameter, if any, and the keyword 
parameters. 

Rest parameter: 

If there is a rest parameter, it is bound to a list of all tlic remaining arguments. If tltere 
are no remaining arguments, it is bound to nil. 

Keyword parameters: 

If there arc keyword parameters, die same remaining arguments are used to bind Uicm, as 
follows. 

The arguments for the keyword parameters are treated as a list of alternating keyword 
symbols and associated values. Bach symbol is matched with eq against the allowed 
parameter keywords, which have by default die same names as the parameters but in the 
keyw/ord package. (You can specify the keyword symbol expliciUy in die lambda list if 
you must; see below.) Often Uie symbol arguments are constants in tlic program, and it is 
convenient for diis usage that keywords all evaluate to Uiemselves, but it is pennissible for 
tliem to be computed by expressions. 

If any keyword parameter has not received a value when all die arguments have been 
processed, the default-form for die parameter is evaluated and die parameter is bound to 
its value. All keyword parameters arc optional. 

There may be a keyword symbol among die arguments which does not match any 
keyword parameter name. By default diis is an error, but die lambda list can specify diet 
diere should be no error using &allow-other-keys. Also, if one of die keyword symbols 
among die arguments is :aliow-other-keys and die value diat follows it is non-nil then 
diere is no error. When diere is no error, for eidicr reason, die non-matching symbols 
and their associated values are simply ignored. The function can access these symbols and 
values dirough the rest parameter, if diere is one. It is common for a function to check 
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Diily for certain keywords, and pass its rest parameter to anotiicr funclion using apply; 
tliat I'lMiction will check for the keywords that concern it. 

'I"hc way yon express which parameters are required, optional, rest and keyword is by means 
of specially recognized symbols, which arc called &- keywords, in the lambda list. All such 
symbols' print names begin with the character '&'. A list of all such symbols is the value of the 
symbol lambda- list-keywords. 

The keywords used here are &key. &optional and Srest. The way they are used is best 
explained by means of examples; the following are typical lambda lists, followed by descriptions 
of which parameters are positional, rest or keyword; and required or optional. 

(a b c) a, b, and c are all required and positional. The function must be passed three 

arguments. 

(a b &optional c) 

a and b arc required, c is optional. All Uirec arc positional. The function may 
be passed citlicr two or three arguments. 

{&optional a b c) 

a, b, and c arc all optional and positional. The function may be passed zero, 
one, two or Uircc arguments. 

(&rest a) a is a rest parameter. The function may be passed any number of arguments. 

(a b &optional c d &rest e) * 

a and b arc required positional, c and d arc optional positional, and e is rest. 
The function may be passed two or more arguments. 

(&key a b) a and b are both keyword parameters, A typical call would look like 

(foo :b 69 :a '(some elements)) 
or 

(foo :a '(some elements) :b 69) 
or 

(foo :a '(some elements)) 
This illustrates that the parameters can be matched in cither order, or omitted. If 
a keyword is specified twice, the first value is used. 

(x Sfoptional y &rest z &key a b) 

X is required positional, y is optional positional, z is rest, and a and b are 
keyword. One or more arguments are allowed. One or two arguments specify 
only the positional parameters. Arguments beyond tlic second specify both the 
rest parameter and tlie keyword parameters, so that 

(foo 1 2 :b '(a list)) 
specifics 1 for x, 2 for y, (:b (a list)) for z, and (a list) for b. It does not 
specify a. 

(&rest z &key a b c &al low-other-keys) 

z is rest, and a, b and c are keyword parameters. &allow-other-keys says that 
absolutely any keyword symbols may appear among tlic arguments; these symbols 
and the values that follow them have no effect on tlie keyword parameters, but 
do become part of tlie value of z. 



PS;<I..!V!AN>FI>HVA.TFXr.46 8-JUN-84 



•unclions 42 I, isp Machine Miinual 



(&rest z &key &al low -other-keys ) 

This is cquivalciii to (&rest z). So, for thai matter, is the previous example, if 
the fiinctioii docs not use the values of a, b and c. 

Ill all of the cases above, the licjault-foiw for each optional parameter is nil. To specify your 
own default forms, instead of putting a symbol as the element of a lambda list, put in a list 
whose first element is the symbol (the parameter itsell) iuid whose second element is the default- 
form. Only optional parameters may have default forms; required parameters are never defaulted, 
and rest parameters always default to nil. I'or example: 

(a &optional (b 3)) 

ihc default-fomi for b is 3. a is a required parameter, and so it doesn't have a 
default form. 

(&optional (a 'foo) &rest d &key b (c (symeval a))) 

a's default-form is 'foo, b's is nil, and c's is (symeval a). Note tliat if the 
function were called on no arguments, a would be boimd to the symbol foo, and 
c would be boimd to the value of the symbol foo; tliis illustrates the fact that 
each variable is bound immediately after its default-form is evaluated, and so later 
default-forms may take advantage of earlier parameters in the lambda list, b and 
d would be bound to nil. 

Occasionally it is important to know whether a certain optional parameter was defaulted or 
not. Just by looking at tlie value one cannot distinguish between omitting it and passing the 
default value explicitly as an argument. The way to tell for sure is to put a tliird element into 
the list: the tliird element should be a variable (a symbol), and tliat variable is bound to nil if 
the parameter was not passed by tlie caller (and so was defaulted), or t if the parameter was 
passed. The new variable is called a "supplied-p" variable; it is bound to t if the parameter is 
supplied. For example: 

(a &optional (b 3 c)) 

ITic default- form for b is 3, and tlie supplicd-p variable for b is c. If the 
ftinction is called with one argument, b is bound to 3 and c is bound to nil. If 
the function is called with two arguments, b is bound to the value that was 
passed by the caller (which might be 3), and c is bound to t. 

It is possible to specify a keyword parameter's symbol independently of its parameter name. 
1\} do til is, use two nested lists to specify the parameter. 'I'he outer list is tlie one which can 
contain the default-form and supplied-p variable, if the parameter is optional. The first element 
of this list, instead of a symbol, is again a list, whose elements are the keyword symbol and the 
parameter variable name. For example: 

(&key ((:a a)) ((:b b) t)) 

This is equivalent to (&key a (b t)). 

(&key ((:base base-value))) 

This defines an argument which callers specify with the keyword :base, but which 
within tlie function is referred to as die variable base-value so as to avoid 
binding the value of base, which is a synonym for *print-base* and controls 
how numbers arc printed. 
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It is iilso possible lo include, in tiie lambda list, some other symbols, which are bound lo the 
values of their default-forms upon entry to the function. These are no! parameters, and they arc 
never bound to arguments; they just get bound, as if they appeared in a let* form. (Whether 
you use aiix-variables or bind the variables with let* is a stylistic decision.) 

To include such symbols, put them after any parameters, precccded by ihc &-kcyword &aux. 
I'lxamplcs: 

(a &optional b &rest c &aux d (e 5) (f (cons a e))) 

d, e, and f arc bound, when ihc function is called, to nil, 5, and a cons of the 
first argument and 5. 

Vou could, cquivalently, use (a &optional b &rest c) as the lamda list and write 
(let* (d (e 5) (f (cons a e))) ...) around the body of the function. 

It is important to rcali/.c tliat the list of arguments to which a rest-parameter is bound is set 
up in whatever way is most efficiently implemented, rather than in the way that is most 
convenient for tlic function receiving the arguments. It is not guaranteed to be a "real" list. 
Sometimes the rcst-args list is a stack list (sec section 5.9, page 112) stored in the function-calling 
suick, and loses its validity when the function returns. If a rest-argument is to be returned or 
made part of permanent list-structure, it must first be copied (sec copylist, page 94), as you must 
always assume that it is one of these special lists. The system does not detect the error of 
omitting to copy a rest-argument; you will simply find tliat you have a value which seems to 
change behind your back. 

At other times the rest-args list may be an argument tliat was given to apply; tliercfore it is 
not safe to rplaca this list as you may modify pennancnt data structure. An attempt to rplacd a 
rest-args list is unsafe in tJiis case, while in tlie first case it would cause an error, since lists in 
the stiick are impossible to rplacd. 

lambda-parameters- limit Constant 

Has as its value tlie limit on the number of parameters tliat a lambda list may have. The 
implementation limit on tlie number of parameters allowed is at least this many, lliere is 
no promise that this many is forbidden, but it is a promise that any number less than this 
many is permitted. 

3.3.1 Lambda-List Keywords 

This section documents all tlie keywords that may appear in the lambda list or argument list 
(see section 3.3, page 38) of a function, a macro, or a special form. Some of them arc allowed 
everywhere, while others arc only allowed in one of tliesc contexts; those are so indicated. You 
need only know about &optlonal, &key, and &rest in order to understand the documentation of 
system fimctions in this manual. 
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lambda- Ust-keywords Comtani 

The viihic of this variable is a lisi of all of the allowed '&" keywords. A list of ihcm 
follows. 



&optional 



&rest 



&key 



Separates the required argmncnis of a function from the optional arguments. See 
section 3.3, page 38. 

Separates the required and optional arguments of a function from the rest 
argument, ilicre may be t)iily one rest argument. See page 41 for full 
informalit)n about rest arguments. See section 3.3, page 38. 

Separates the positional arguments and rest argimient of a function from the 
keyword arguments. See section 3.3, page 38. 



Sallow -other -keys 

In a function (hat accepts keyword arguments, says that keywords that are not 
recogni/.ed are allowed. They and the corresponding Nalues are ignored, as far as 
keyword arguments are concerned, but they do become part of the rest argument, 
if tlierc is one. 



&aux 



&special 

&local 
&quote 

&eval 

&list-of 

&body 

&whofe 



Separates the arguments of a function from the auxiliary variables. Following 
&aux you can put entries of the fomi 

{ variable initial- value- form ) 
or just variable if you want it initialized to nil or don't care what the initial value 
is. 

Declares tJie following arguments and/or auxiliary variables to be special within 
tlic scope of iliis function. 

Turns off a preceding Sspecial for the variables that follow. 

Declares tliat the following arguments are not to be evaluated. This is how you 
create a special function. See the caveats about special forms on page 233. 

Turns off a preceding &quote for the arguments which follow. 

This is for macros defined by defmacro only. Refer to page 324. 

This is for macros defined by defmacro only. It is similar to &rest, but declares 
to grindef and the code-formatting module of the editor tliat the body forms of a 
special fonn follow and should be indented accordingly. Refer to page 324. 

This is for macros defined by defmacro only. It means that the following 
argument is bound to the entire macro call form being expanded. Refer to page 
324. 



&environment This is for macros defined by defmacro only. It means that the following 
argument is bound to an environment structure which records the local macrolet 
macro definitions in effect for subforms of the macro call form. Refer to page 
324. 
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3.3.2 Local Functions 

The consiiucls flet and labels permit you to define a function name in a lexical context only. 
If the same name has a global function definition, it is shadowed temporarily. I -unction 
definitions established by flet (or labels) are to global definitions made with defun as lexical 
variable bindings made with let arc to global bindings made with defvar. They always have 
lexical scope. 

flet local- fuiwllous body... Special form 

H'xecutes body with local function definitions in effect according to local-Jhnciioiis. 

hcahfunc/ions should be a list of elements which look like 

{name lambda-lisi function-body. . .) 
just like ihe cdr of a defun form. The meaning of this element of local-functions is to 
define name locally with the indicated definition. Within the lexical scope of body, using 
name as a function name accesses the local definition. 

Example: 

(flet ((triple (x) {* X 3))) 

(print (triple -1)) 

(mapcar (function triple) '(1 2 1.2))) 
prints tlie number -3 and returns a list (3 6 3.6). 

Each local function is closed in the environment outside tlic flet. As a result, tlic local 
functions cannot call each other. 

(flet ((foo (x) (bar x t)) 

(bar (y z) (list y z))) 
(foo t)) 
calls tlie local definition of foo, which calls the global definition of bar, because the body 
of foo is not within tlic scope of the local definition of bar. 

Functions defined with flet inside of a compiled function can be referred to by name in a 
function spec of the fomi (:internal outer-function- name flet- name). See page 226. 

labels local- functions body... Special form 

Is like flet except that the local fiinctions can call each other. They arc closed in the 
environment inside tlic labels, so all Uie local function names are accessible inside the 
bodies of tlie local fimctions. labels is one of tlie most ancient Lisp constructs, but was 
typically not implemented in second generation Lisp systems in which no efficient form of 
closure existed. 

(labels ((walk (x) 

(typecase x 

(cons (walk (car x)) (walk (cdr x))) 
(t (if (eq X 'haha) (print 'found-it)))))) 
(walk foo)) 
allows walk to call itself recursively because walk's body is inside the scope of the 
definition of walk. 
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Soc also macrolet, an analogous consliiicl for dcfniing macros locally (page 329). 

3.4 Some runctions and Special rorms 

This section describes sonic funciions and special forms. Some are pans of the evaluator, or 
closely related to it. Some have to do specifically with issues discussed above such as keyword 
arguments. Some are just fundamental Lisp forms that are very important. 

eval fonii &optional noliovk 

{e\/a\ form) evaluates /m;/. and returns the result. 
I'lxamplc: 

(defvar x 43) 
(defvar foo 'bar) 
(eval (list 'cons x 'foo)) 
=> (43 . bar) 
Ihe dynamic bindings available at the time eval is called are visible for dynamic variables 
within die expression x. No lexical bindings arc available for tlie evaluation of x. 

it is unusual to call eval explicitly, since usu^iUy evaluation is done implicitly. If you are 
writing a simple I.isp program and explicitly calling eval, you are probably doing 
something wrong, eval is primarily useful in programs which deal with Lisp itself, rather 
than programs about knowledge, matliematics or games. 

Also, if you arc only interested in getting at the dynamic value of a symbol (that is, die 
contents of the symbol's value cell), then you should use the primitive function symeval 
(sec page 129). 

If the argument nohook is non-nil, exccudon of die evalhook is inhibited for fonn, but 
not for evaluation of the subforms of fonn. See evalhook, page 749. evalhook is also 
die way to evaluate in a specified lexical environment if you happen to have got your 
hands on one. 

Note: in Maclisp, die second argument to eval is a "binding context pointer". There is 
no such thing in Zctalisp; closures are used instead (see chapter 12, page 250). 

si:evall fonn &optional nohook 

Within die definition of a special form, evaluates fonn in die current lexical environment. 

fun call / &rcst orgs 

(funcall f al a2 ... an) applies the flmction /to die arguments al, a2, ..., an. /may 

not be a special form nor a macro; diis would not be meaningful. 

Example: 

(cons 1 2) => (1 . 2) 

(setq cons 'plus) 

(funcall cons 1 2) => 3 
ITiis shows diat die use of die symbol cons as the name of a function and die use of 
that symbol as die name of a variable do not interact. 'ITie cons form invokes die 
function named cons. The funcall form evaluates die variable and gets the symbol plus. 
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which is ihc name of a diHercnl functii)n. 

Note: the Maclisp functions subrcall, Isubrcall, and arraycall arc not needed on the I. isp 
Machine; funcall is just as clTicicnt. arraycall is provided for compatibility; it ignores its first 
subform (the Maclisp array type) and is otherwise identical to aref. subrcall and Isubrcall arc 
not provided. 

apply / ^''cst ari;s 

lexpr-funcall / &rest args 

apply is like funcall except that the last of ar^s is really a list of argimients to give to / 
rather than a single argument, lexpr-funcall is a synonym for apply; formerly, apply 
was limited to the two argument case. 

{apply f arglisi) applies the function /to the list of arguments arglisl. arglist should be a 

list; /can be any function. 

Examples: 

(setq fred '+) (apply fred '(1 2)) => 3 

(setq fred ' -■ ) (apply fred '(1 2)) => -1 

(apply 'cons '((+ 2 3) 4)) => 

((+ 2 3) . 4) not {5 . A) 
Of course, arglist may be nil. 

If there is more than one clement of args, tJicn all but the last of tJicm arc individual 

arguments to pass to /, while tlic last one is a list of arguments as above. 

Examples: 

(apply 'plus 1 1 1 '(1 1 1)) => 6 

(defun report-error (&rest args) 

(apply 'format *error-output* args)) 

apply can also be used with a single argument. Then this argument is a list of a function 

and some arguments to pass it. 

Example: 

(apply '(car (a))) => a 

;Not the same as (eval '(car (a))) 

Note: in Maclisp, apply takes two or three arguments, and the tJiird argument, when 
passed, is interpreted as a "binding context pointer". So the second argument always 
provides all the args to pass to the function. There are no binding context pointers in 
Zetalisp; true lexical scoping exists and is interfaced in other ways. 

call -arguments -limit Constant 

Has as its value the limit on the number of arguments that can be dealt with in a 
function call. There is no promise that this many is forbidden, but it is a promise that 
any smaller number is acceptable. 

Note that if apply is used with exactly two arguments, the first one being a function that 
takes a rest argument, there is no limit except the size of memory on the number of 
elements in tlie second argument to apply. 
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call fund ion &rcsi argumcnt-sjuxijkntions 

OITcrs a very general way of controlling what arguinenis you pass to a function. You can 
provide eilhcr individual arguments as in funcall or lists of arguments as in apply, in any 
order. In addition, you can make some of ihe arguments optional. If the function is not 
prepared to accept all the arguments you specify, no error occurs if the excess arguments 
are optional ones. Instead, Lhe excess arginnents arc simply not passed to Llie function. 

The (ir^iumrni'spccs are alternating keywords (or lists of keywords) and values. K,ach 
keyword or list of keywords says what to do with the value lliai follows. If a value 
happens to require no keywords, provide () as a list of keywords for it. 

Two keywords are presently defined: :optional and .spread. :spread says that tlic 

following value is a list of arguments. Otherwise it is a single argument. :optional says 

that all the following arguments arc optional. It is not necessary to specify :optional with 
all the following argunienl-spccs, because it is sticky. 

Hxample: 

(call #'foo () X rspread y '(roptional .-spread) z () w) 
The arguments passed to foo arc the value of x, the elements of the value of y, the 
elements of the value of z, and ilic value of w. The function foo must be prepared to 
accept all the arguments which come from x and y, but if it does not want die rest, they 
arc ignored. 

quoto object Specialfonn 

(quote object) simply returns object, quote is used to include constants in a fonn. It is 
useful specifically because object is not evaluated; the quote is how you make a form that 
returns an arbitrary Lisp object. 
Examples: 

(quote x) => X 

(setq X (quote (some list))) x => (some list) 

Since quote is so useful but somewhat cumbersome to type, the reader nonnally converts 
any form preceded by a single quote ( ' ) character into a quote form. 
For example, 

(setq X '(some list)) 
is converted by read into 

(setq X (quote (some list))) 

function / Special form 

function has two distinct, though related, meanings. 

Jf / is a symbol or any other function spec (see section 11.2, page 223), (function f) 
refers to the function definition of f. For example, in (mapcar (function car) x), the 
function definition of car is passed as tlie first argument to mapcar. function used this 
way is like fdefinition except that its argument is unevaluated, and so 
(function fred) islike (fdefinition 'fred) 
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y\an also be an explicit function, or lanihda-cxpression. a list such as (lambda (x) (* x 
x)) such as could be the function definition of a symbol. Then (function f) represents 
that function, suitably interfaced to execute in the lexical environment where it appears. 
To explain: 

(let (a) 

(mapcar (lambda (x) (push x a)) 1)) 

attempts to call the function lambda and evaluate (x) for its first argument. That is no 
way to refer to the function expressed by (lambda (x) (push x a)). 

(let (a) 

(mapcar (quote (lambda (x) (push x a))) 1)) 

passes to mapcar the list (lambda (x) (push x a)). This list does not in any way record 
the lexical environment where the quote form appeared, so it is impossible to make tliis, 
environment, with its binding of a, available for tlic execution of (push x a). Therefore, 
tJic reference to a docs not work property. 

(let (a) 

(mapcar (function (lambda (x) (push x a))) 1)) 

passes mapcar a specially designed closure made from the fimction represented by 
(lambda (x) (push x a)). When mapcar calls this closure, the lexical environment of tlie 
function form is put again into effect, and the a in (push x a) refers properly to the 
binding made by tliis let. 

In addition, the compiler knows tliat the argument to function should be compiled. ITie 
argument of quote cannot be compiled since it may be intended for other uses. 

To ease typing, the reader converts ^Uhing into (function ///mg). So #' is similar to ' 
except that it produces a function form instead of a quote form. The last example could 
be written as 

(let (a) 

(mapcar #'(lambda (x) (push x a)) 1)) 

Another way of explaining function is that it causes / to be treated the same way as it 
would as the car of a form, livaluating tlie form if argi arg2...) uses tlie fimction 
definition of / if it is a symbol, and otherwise expects / to be a list which is a lambda- 
expression. Note that the car of a form may not be a non-symbol function spec, as that 
would be difficult to make sense of. Instead, write 
(funcall (function spec) args...) 

You should be careful about whether you use #' or '. Suppose you have a program 
with a variable x whose value is assumed to contain a function tliat gets called on some 
arguments. If you want that variable to be the test function, there are two things you 
could say: 
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(setq X 'test) 
or 

(setq X ^'test) 
The former causes the value of x to be the symbol test, whereas tlic latter causes the 
value of X to be the function object found in the function cell of test. When the time 
comes to call the function (the program does (funcall x ...)), either expression works 
because calling a symbol as a function uses its function definition instead. Using 'test is 
insignificantly slower, because the function call has to indirect through the symbol, but it 
allows the function to be redefined, traced (see page 7.18), or advised (see page 742). Use 
of #' picks up the fimciion definition out of the symbol test when the setq is done and 
does not see any lalcr changes to it. #' should be used only if you wish specifically to 
prevent redefinition of the function from afiecting this closure. 



falsa 



true 



Takes no arguments and returns nil. 



"akcs no arguments and returns t. 



ignore &rest ignore 

Takes any number of arguments and returns nil. Hiis is often useful as a "dummy" 
function; if you arc calling a function that takes a function as an argument, and you 
want to pass one that doesn't do anything and won't mind being called with any argument 
pattern, use this. 

c mme n t Special fonn 

comment ignores its form and returns the symbol comment. It is most usefiil for 
commenting out function definitions that are not needed or correct but worth preserving 
in the source. The #|...|# syntactic constnict is an alternative method. For comments 
within code about the code, it is better to use semicolons. 
Example: 

(comment 

;; This is brain-damaged. Can someone figure out 

;; how to do this right? 

(defun foo (x) 

) ;End comment 

;; prevents this definition of foo from being used. 
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3.5 Declarations 

Declarations provide auxiliary intbrnialion on how to execute a function or expression 
properly. The most important declarations are special declarations, which control the scope of 
variable names. Some declarations do not aiTect execution at all and only provide information 
about a fimction, for the sake of arglist for example. 

Declarations may apply to an entire function or to any expression within it. Declarations can 
be made around any subexpression by writing a local -declare around tlic subexpression or by 
writing a declare at the front of the body of certain constructs. Declarations can be made on an 
entire function by writing a declare at the front of the function's body. 

local -declare {dcdanilUm...) body... Special form 

A local -declare form looks like 

( local -deal are {decll decl2 ...) 
fortnl 
fonn2 

Etich decl is in effect for the forms in the body of tlic local- declare form. 

declare declaration... Special fonn 

'I'hc special fonn declare is used for writing local declarations within the construct they 
apply to. 

A declare inside a fimction definition, just after the argument list, is equivalent to putting 
a local -declare around the function definition. More specifically, 

(defun foo (a b) 

(declare (special a b)) 
(bar)) 

is equivalent to 

(local-declare ((special a b)) 
(defun foo (a b) 
(bar))) 

Note that 

(defun foo (a b) 

(local-declare ((special a b)) 
(bar))) 

docs not do the job, because the declaration is not in effect for the binding of the 
arguments of foo. 
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declare is preferable lo local-declare in this sort of siliialion, because it allows tlic 
defuns iheniselves lo be ihe i()p-le\cl lisis in the file. While local -declare might appear 
lo have an advanuige in that one local-declare may go around several defuns, it tends 
to cause trouble to use local -declare in ihat fashion. 

declare has a similar meaning at the fVont of the body of a progn, prog, let, prog*, 
let*, or internal lambda. I "or example, 
(prog (x) 

(declare (special x)) 

• • • ) 
is equivalent to 

(local-declare ((special x)) 
(prog (x) 

At top level in the file, (declare forms...) is equivalent to (eval-when (compile) 
forms...), ibis use of declare is nearly obsolete, and should be avoided. In Common 
l.isp, proclaim (below) is used for such purposes, with a different calling convention. 

Klscwherc, declare's arc ignored. 

Here is a list of declarations that have system-defined meanings: 

(special varl var2 ...) 

The variables varf var2, etc. will be treated as special variables in the scope of 
tlie declaration. 

(unspecial v^r/ vGr2...) 

The variables varl, var2, etc. will be treated as lexical variables in the scope of 
the declaration, even if tlicy are globally special. 

(T\oX\n\'inefunlfun2...) 

Ilie fi.mctions/w/;/, fun2 and so on will not be open coded or optimized by the 
compiler within the scope of the declaration. 

{Inline fun 1 fun2 ...) 

llie flmctions fun J, fun2 and so on will be open coded or optimized by the 
compiler (to whatever extent it knows how) within the scope of the declaration. 
Merely issuing this declaration docs not tell tlie compiler how to do any useful 
optimization or open coding of a function. 

[Ignore varl var2 ...) 

Says that the variables varl, var2, etc., which are bound in the construct in 
which tliis declaration is found, arc going to be ignored, lliis is currently 
significant only in a function being compiled; tlic compiler issues a warning if the 
variables arc used, and refrains from its usual warning if the variables are ignored. 

(declaration decU dccU ...) 

Says tliat declarations decU, decl2, etc. arc going to be used, and prevents any 
warning about an unrecognized type of declaration. For example: 
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(defun hack ( ) 

(declare (declaration lose-method) 

(lose-method foo bar)) 
... ( lose foo) ...) 
might be iisefui if (lose foo) is a macro whose expander function does (getdecl 
'too 'lose-method) to sec what to do. See page 307 for more information on 
getdecl and declarations. 

(proclaim '(declaration lose-method)) 
might also be advisable if you expect widespread use of lose-method declarations. 

The next two arc used by the compiler and generally should nt)t be written by users. 

(def nafnc . dcfmUUm) 

name will be defmcd for the compiler in the scope of tlic declaration. The 
compiler uses this automatically to keep track of macros and open-codablc 
functions (defsubsts) defined in tJie file being compiled. Note tJiat tJic cddr of 
this item is a function. 

{propmvne symbol value) 

(getdecl symbol propname) will return value in tlic scope of tlic declaration. This 
is how tlic compiler keeps track of defdecls. 

These declarations are significant only when tliey apply to an entire defun. 

(arglist . arglisi) 

Records arglisi as the argument list of the ftmction, to be used instead of its 
lambda list if anyone asks what its arguments arc. This is purely documentation. 

(values . values) or (: return -list . values) 

Records values as the return values list of the function, to be used if anyone asks 
what values it returns. This is purely documentation. 

(sys:f unction - parent parent-function- spec) 

Records parent-function-spec as the parent of tliis fiinction. If, in the editor, you 
ask to see tlie source of this function, and the editor doesn't know where it is, 
tlic editor will show you tJic source code for die parent function instead. 

For example, the accessor functions generated by defstruct have no defuns of 
tlieir own in the text of the source file. So defstruct generates them with 
sys:functJon- parent declarations giving the defstruct's name as the parent 
function spec. Visiting die accessor function with Meta-. sees the declaration and 
therefore visits the text of the defstruct. 

(:se\f-Myorflavorname) 

Instance variables of the flavor flavorname, in self, will be accessible in the 
function. 



PS:<I ..M AN>Fl>HVA.TFXr.46 8-JUN-84 



Declaralions 54 I isp Machine M^iiuial 



locally &body body Macro 

l^xeciilcs the body, rccogni/ing declaralions al the from of it. locally is syiionyiTioiis with 

progn except tliai in Common Lisp a declare is allowed at the beginning of a locally 
and not at the beginning of a progn. 

locally does dilTer from progn in one context: at top level in a file being compiled, 
progn causes each of its elements (including declaralions, therefore) to be treated as if at 
top level, locally does not receive this irealmenl. The locally form is simply evaluated 
when the O'ASI. file is loaded. 

proclaim &resi declarations 

|{ach of declarations is put into elTecl globally. Currently only special and unspecial 
declarations mean anything in this way. proclaim's argumenis are evaluated, and the 
values are expected to be declarations such as you could write in a declare. Thus, you 
would say (proclaim '(special x)) to make a special declaration globally. 

Top-level special declarations arc not the recommended way to make a variable special. 
Use defvar, defconstant or defparameter, so that you can give tlic variable 
documentation. Proclaiming the variable special should be done only when tlie variable is 
used in a file other than tlie one which defines it, to enable the file to be compiled 
without having to load tlie defining file first. 

proclaim is fairly new. Until recently, top-level declare was the preferred way to make 

global special declarations when defvar, etc., could not be used. Such top-level declare's 

are still quite common. In them, the declaration would not be quoted; for example, 
(declare (special x)). 

special variables... Special fonn 

Fquivalent to (proclaim (special variables...)), this declares each of tlie variables to be 
globally special. This flmction is obsolete. 

unspecial variables. . . Special fonn 

Removes any global special declarations of the variables. This function is obsolete. 

the type- specifier value- fjrtn Macro 

Is a Common Lisp constmct effectively the same as value-fonn. It declares that the value 
of value-fonn is an object which of type type- specifier, lliis is to assist compilers in 
generating better code for conventional machine architectures. The Lisp Machine does not 
make use of type declarations so this is the same as writing just value-fonn. type-specifier 
is not evaluated. 

If you want the type of an object to be checked at run time, with an error if it is not 
what it is supposed to be, use check -type (page 709). 
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3.6 I ail Recursion 

When one function ends by calling another function (possibly itself), as in 
(defun last (x) 
(cond ( (atom x) x) 

( (atom (cdr x) ) x) 
(t (last (cdr x))))) 

it is called (ail recursion. In general, if A' is a form, and )' is a sub-form of A', then if the 
value of )' is unconditionally returned as the value of A', with no intervening computation, then 
we say that X tail-recursively evaluates Y. 

In a tail recursive situation, it is not strictly necessary to remember anything about tJie first 
call to last when the second one is activated. The stack frame for the first call can be discarded 
completely, allowing last to use a bounded amount of stack space independent of the length of 
its argument. A system which docs this is called tail recursive. 

The Lisp machine system works tail recursively if the variable tail -recursion -flag is non-nil. 
lliis is often fiistcr, because it reduces the amount of time spent in refilling tJie hardware's pdl 
buffer. However, you forfeit a certain amount of useful debugging information: once tlic outer 
call to last has been removed from die suxk, you can no longer see its frame in tlic debugger. 

tan -recursion-flag Variable 

If this variable is non-nil, the calling stack frame is discarded when a tail-recursive call is 
made in compiled code. 

There are many things which a function can do Uiat can make it dangerous to discard its 
suick frame. P^or example, it may have done a *catch; it may have bound special variables; it 
may have a &rest argument on die stack; it may have asked for the location of an argument or 
local variable. The system detects all of tiicse conditions automatically and reUiins Uie stack frame 
to ensure proper execution. Some of diese conditions occur in eval; as a result, interpreted code 
is never coinpletely tail recursive. 

3.7 Multiple Values 

^rhe Lisp Machine includes a facility by which the evaluation of a form can produce more 
than one value. When a function needs to return more than one result to its caller, multiple 
values are a cleaner way of doing Uiis tlian returning a list of the values or setq'ing special 
variables to die extra values. In most Lisp function calls, multiple values arc not used. Special 
syntax is required both to produce multiple values and to receive them. 

The primitive for producing multiple values is values, which Uikes any number of arguments 
and returns that many values. If Uie last form in die body of a function is a values with Uiree 
arguments, dien a call to diat function returns dircc values. Many system ftmctions produce 
multiple values, but dicy all do it via values. 
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values &rcst ^//-^.v 

RcUirns nuilliplc values, its argumcms. This is the primitive fuiictiDn for producing 
multiple values. It is legal to call values v^ith no arguments: it returns no values in that 
case. 

va1u9S-Hst list 

Returns multiple values, the elements of the lisl. (values- list '(a b c)) is the same as 
(values 'a 'b 'c). list may be nil, the empty list, u/hich causes no values to be returned, 
liquivalenl to (apply 'values list). 

return and its variants can also be used, within a block, do or prog special form, to return 
multiple values. They are explained on page 77. 

Here are the special forms for rccei\ing nuiltiplc values. 

multiple-value {variable...) form Special fonn 

mul t Iple-value-setq {variable...) form Special fonn 

multiple-value is a special form used for calling a function which is expected to return 
more than one value, fonn is evaluated, and the variables arc set (not lambda-bound) to 
the values returned by fonn. If more values are returned than there arc variables, the 
extra values arc ignored. If there are more variables than values returned, extra values of 
nil are supplied. If nil appears in tlic vai-list, then tlic corresponding value is ignored 
(setting nil is not allowed anyway). 
Example: 

(mul tiple- value (symbol al ready-there-p) 
(intern "goo")) 
In addition to its first value (the symbol), intern returns a second value, which is non-nil 
if an existing symbol was found, or else nil if intern had to create one. So if the symbol 
goo was already known, tlic variable already-there-p is set non-nil, otherwise it is set to 
nil. The tliird value returned by intern is ignored by tliis fonn of call since there is no 
third variable in the multiple-value. 

multiple-value is usually used for effect rather than for value; however, its value is 
defined to be the first of the values returned by form. 

multiple-value-setq is the Common Lisp name for this construct. The two names are 
equivalent. 

multilple-value-blnd {variable...) fonn body... Special fonn 

This is similar to multiple-value, but locally binds the variables which receive the values, 
raUier than setting them, and has a body — a set of forms which arc evaluated with these 
local bindings in effect. First fonn is evaluated. Then the variables are bound to the 
values returned by form. 'Ilien tlie body forms are evaluated sequentially, tlie bindings 
are undone, and tlic result of the last body form is returned. 
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Kxample: 

(multi pie- value- bind ( sym al ready -the re) 
(intern string) 
;; If an existing symbol was found, deallocate the string, 
(if already-there 

(return-storage (progl string (setq string nil)))) 
sym) 

multiple-value-call fund ion (nxfonm... Special form 

Iwakialcs ihc argforiTis, saving all of their values, and then calls function with all iJiosc 
values as arguments. This differs from 

(fun call function art^orms. . .) 
because that would get only one argument for function from each argfonn, whereas 
multiple-value-call gets as many args from each argfonn as the argform cares to return. 
Ihis works by consing a list of all the values returned, and applying function to it. 
Hxamplc: 

(multiple-value-call 'append 
(values '(a b) '(c d)) 
'{e f)) 
=> (a b c d e f) 

multiple-value- progl fowi fonm... Special form 

Evaluates form, saves its values, evaluates the forms, discards their values, then returns 
whatever values form produced. This does not cons. Example: 
(multiple-value-progl (values 1 2) 
(print 'foo)) 
=> 1 2 

multiple-value-list form Special form 

multiple-value-list evaluates form, and returns a list of tlic values it returned. This is 

useful for when you don't know how many values to expect. 

Example: 

(setq a (multiple-value-list (intern "goo"))) 

a => (goo nil #<Package USER 10112147>) 
This is similar to the example of multiple-value above; a is set to a list of three 
elements, the three values returned by intern. 

nth-value « /om? Specialform 

Evaluates form and returns its value number n, n = meaning the first value. For 
example, (nth- value 1 (foo)) returns the second of foo's values, nth -value operates 
without consing in compiled code if tlie first argument's value is known at compile time. 

When one form finished by tail recursively evaluating a subform (see section 3.6, page 55), all 
of the subform's multiple values are passed back by tlic outer form. For example, the value of a 
cond is tlie value of the last fonn in tlie selected clause. If the last forni in that clause produces 
multiple values, so does the cond. 'lliis passing-back of multiple values of course has no effect 
unless eventually one of the special forms for receiving multiple values is reached. 
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If llic oilier Ibrni rcimiis a value computed by a subfomi, but not in a tail recuisivc fashion 
(lor example, if the \alue of the sublbrm is examined first), multiple \alues or only single values 
may be returned at the discretion of the implementation; users should not depend on whatever 
way it happens lo work, as it may change in the future or in other implementations. Ihc reason 
we don"l guarantee non-transmission of multiple values is because such a guarantee would not be 
very useliil and the elficiency cost of enft)rcing it would be high. I-Acn setq'ing a variable to the 
result i)f a form, then returning the value of that variable, might pass multiple values if an 
optimizing compiler realized that the setq'ing of the \ariable was unnecessary. Sjnce extra 
returned values are generally ignored, it is not vital lo eliminate tliem. 

Note that use of a form as an argument lo a function never receives multiple values from that 
form. That is, if the form (too (bar)) is evaluated and the call to bar returns many values, too 
is still called on only one argument (namely, the first value returned), rather than being called on 
all the values returned. We choose not lo generate several separate arguments from the several 
values, because tliis would make the source code obscure; it would not be syntactically obvious 
that a single form docs not correspond to a single argument. To pass all returned values to 
another function, use multiple -value-call, above. 

Por clarity, descriptions of the interaction of several common special forms with multiple 
values follow. This can all be deduced from tlie rule given above. Note well that when it says 
tliat multiple values are not returned, it really means tliat tliey may or may not be returned, and 
you should not write any programs diat depend on which way it actually works. 

The body of a defun or a lambda, and variations such as the body of a function, the body 
of a let, etc., pass back multiple values from the last form in the body. 

eval, apply and funcall, pass back multiple values from tlie function called. 

progn passes back multiple values from its last form, progv and progw do so also, progl 
and prog2, however, do not pass back multiple values. 

Multiple values are passed back only from the last subform of an and or an or form, not 
from previous subforms since tlic return is conditional. Remember tliat multiple values arc only 
passed back when the value of a subform is unconditionally returned from the containing form. 
F'or example, consider the form (or (foo) (bar)). If foo returns a non-nil first value, then only 
that value is returned as the value of the form. But if it returns nil (as its first value)^ tlien or 
returns whatever values the call to bar returns. 

cond passes back multiple values from the last form in the selected clause, providcci that that 
last fonn's value is returned unconditionally. This is true if the clause has two or more forms in 
it, and is always true for tlie last clause. 

nic variants of cond such as If, select, selectq, and dispatch pass back multiple values 
from ihc last form in the selected clause. 

If a block form falls through the end, it returns all the values returned by the last Expression 
in it. If return -from or return is used to exit a block form, then the values returncjd by the 
block form depend on tlic kind of return. If return is given two or more subforms, then block 
returns as many values as tlie return has subforms. However, if tlie return has only one 
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subforiTi, then the block rctm-ns all of llic values returned by thai one sublbrin. 

prog behaves like block if il is exited with return (or return -from). If control falls through 
the end of a prog, it returns the single value nil. do also behaves like block with respect lo 
return, but il" it is exited through the exit test, all the values of ihe last cxii-form are returned. 

unwind -protect passes back multiple values from its protected form, in a sense, this is an 
exception to the rule; but it is useful, and it makes sense to consider the execution of the 
unwind forms as a byproduct of unwinding the stack and not as part of sequential execution. 

catch passes back multiple values from the last form in its body, if it exits normally. If a 
throw is done, multiple values are passed back from the value form in the throw. 

multiple-values-Hmlt Cotisiaut 

The smallest number of values that might possibly fail to work. Returning a number of 

values less than this many cannot possibly run into trouble with an implementation limit 
on number of values returned. 

3.8 Evaluation and Function Calling Errors 

Here is a description of die error conditions tliat tlic cvaluator can signal. Some can be 
signaled by calls to compiled functions also. This is for use by tiiosc who are writing condition 
handlers (section 30.2, page 700). The novice should skip this section. 

sys: Invalid-function (error) Condition 

1 his is signaled when an object that is supposed to be applied to arguments is not a valid 
Lisp function. The condition instance supports the operation :function, which returns the 
supposed function to be called. 

The :new-function proceed type is provided; it expects one argument, a function to call 
instead. 

sys:1nval1d-lambda-11st (sys:invalid-function error) Condition 

This condition name is present in addition to sys:invalid -function when tlic function to 
be called looks like an interpreted ftjnction, and the only problem is the syntax of its 
lambda list. 

sys: too-few-arguments (error) Condition 

This condition is signaled when a function is applied to too few arguments. The condition 
instance supports the operations :function and :arguments which return die function and 
the list of tlic arguments provided. 

The proceed types :additional -arguments and :new-argument-list are provided. Both 
take one argument. In the first case, the argument is a list of arguments to pass in 
addition to tlie ones supplied. In the second, it is a list of arguments to replace the ones 
actually supplied. 
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sys: too- many-arguments (error) Coudiihm 

This is similar to sys:t:oo-few-arguments. Insicad of ihc ladditionai- arguments pri)cccd 
type, :fewer-arguments is provided. Its argument is a number, which is hi)w many of 
the originally supplied arguments U) use in calling the finiction again. 

sys: undefined- keyword- argument (error) Condi lion 

This is signaled when a function that ti«kes keyword arguments is given a keyword that it 
does not accept, if &allow-other-keys was not used in the function's definition and 
:allow- other-keys was not specified by the caller (see page 40). The :keyword operation 
on the condition instance returns the extraneous keyword, and the :value operation 
returns the value supplied with it. 

The prweed type :new-keyword is provided, it expects one argument, which is a 
keyword to use instead of the one supplied. 

sys: cell -contents-error (error) Condition Flavor 

This condition name categorizes all the errors signaled because of references to void 
memory locations. It includes "unbound" variables, "undefined" functions, and other 
tilings. 

:address A locative pointer to the referenced cell. 

:current-address 

A locative pointer to the cell which currently contains the contents that 
were found in tlie referenced cell when tlic error happened, 'lliis can be 
din'erent from tlic original address in tlie case of dynamic variable 
bindings, which move between special PDLs and symbol value cells. 

:cell-type A keyword saying what type of cell was referred to: :f unction, :value, 

:closure, or nil for a cell that is not one of those. 

containing -structure 

1 he object (list, array, symbol) inside which the referenced memory cell is 
found. 

:data-type 

pointer The data type and pointer fields of the contents of the memory cell, at 

the time of the error. Both are fixnums. 

The proceed type :no -action takes no argument. If the cell's contents are now valid, the 
program proceeds, using them. Otherwise the error happens again. 

The proceed type :package-dw/im looks for symbols with the same name in other 
packages; but only if tlie containing structure is a symbol. 

Two other proceed types take one argument: :new- value and :store-new-value. Tlie 
argument is used as the contents of the memory cell. :store-new-value also permanently 
stores the argument into tlie cell. 
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sys:unbound-var1able (sys;cell contents error error) i'oudiiion 

riiis condition name catcgori/cs all errors of variables whose values are void. 

sysrunbound-special-variable Condition 

sys; unbound-closure- variable Condition 

sys:unbound -instance-variable Condition 

These condition names appear in addition to sys:unbouncl -variable to siibcategori/e the 

kind of variable reference that the error happened in. 

sys:undef ined-function (sys:cell -contents-error error) Condition 

This condition name categori/.es errors of function specs that arc undefined. 

sysiwrong-type-argument (error) Condition 

This is signaled when a function checks the type of its argument and rejects it; for 
example, if you do (car 1). 

The condition instance supports these extra operations: 

:arg-name I'he name of tlic erroneous argument. Iliis may be nil if there is no 
name, or if tlie system no longer remembers which argument it was. 

:old -value I'hc value tliat was supplied for the argument. 

:function The function which received and rejected the argument. 

:description A type specifier which says what sort of object was expected for this 
argument. 

Tlie proceed type :argument-value is provided; it expects one argument, which is a 
value to use instead of tlie erroneous value. 
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